

    \filetitle{instrument}{Define forecast conditioning instruments in VAR models}{VAR/instrument}

	\paragraph{Syntax to add forecast
instruments}

\begin{verbatim}
V = instrument(V,Def)
V = instrument(V,Name,Expr)
V = instrument(V,Name,Vec)
\end{verbatim}

\paragraph{Syntax to remove all forecast
instruments}

\begin{verbatim}
V = instrument(V)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{V} {[} VAR {]} - VAR object to which forecast instruments will
  be added.
\item
  \texttt{Def} {[} char \textbar{} cellstr {]} - Definition of the new
  forecast conditioning instrument.
\item
  \texttt{Name} {[} char {]} - Name of the new forecast conditiong
  instrument.
\item
  \texttt{Expr} {[} char {]} - Expression defining the new forecast
  conditiong instrument.
\item
  \texttt{Vec} {[} numeric {]} - Vector of coeffients to combine the VAR
  variables to create the new forecast conditioning instrument.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\tightlist
\item
  \texttt{V} {[} VAR {]} - VAR object with forecast instruments added or
  removed.
\end{itemize}

\paragraph{Description}

Conditioning instruments allow you to compute forecasts conditional upon
a linear combinationi of endogenous variables.

The definition strings must have the following form:

\begin{verbatim}
'name := expression'
\end{verbatim}

where \texttt{name} is the name of the new conditioning instrument, and
\texttt{expression} is an expression referring to existing VAR variable
names and/or their lags.

Alternatively, you can separate the name and the expression into two
input arguments. Or you can define the instrument by a vector of
coefficients, either \texttt{1}-by-\texttt{N} or
\texttt{1}-by-\texttt{(N+1)}, where \texttt{N} is the number of
variables in the VAR object \texttt{V}, and the last optional element is
a constant term (set to zero if no value supplied).

The conditioning instruments must be a linear combination (possibly with
a constant) of the existing endogenous variables and their lags up to
p-1 where p is the order of the VAR. The names of the conditioning
instruments must be unique (i.e.~distinct from the names of endogenous
variables, residuals, exogenous variables, and existing instruments).

\paragraph{Example}

In the following example, we assume that the VAR object \texttt{v} has
at least three endogenous variables named \texttt{x}, \texttt{y}, and
\texttt{z}.

\begin{verbatim}
V = instrument(V,'i1 := x - x{-1}','i2: = (x + y + z)/3');
\end{verbatim}

Note that the above line of code is equivalent to

\begin{verbatim}
V = instrument(V,'i1 := x - x{-1}');
V = instrument(V,'i2: = (x + y + z)/3');
\end{verbatim}

The command defines two conditioning instruments named \texttt{i1} and
\texttt{i2}. The first instrument is the first difference of the
variable \texttt{x}. The second instrument is the average of the three
endogenous variables.

To impose conditions (tunes) on a forecast using these instruments, you
run \href{VAR/forecast}{\texttt{VAR/forecast}} with the fourth input
argument containing a time series for \texttt{i1}, \texttt{i2}, or both.

\begin{verbatim}
j = struct();
j.i1 = tseries(startdate:startdate+3,0);
j.i2 = tseries(startdate:startdate+3,[1;1.5;2]);

f = forecast(v,d,startdate:startdate+12,j);
\end{verbatim}


